Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d2 / sd60.arc / SDR.DOC < prev next >

Wrap

Text File | 1989-01-06 | 31.4 KB | 650 lines

------------------------------------------------------------------------ SDR: IBM-PC Resident Sorted Directory Utility V6.0 Copyright (C) 1986-89 By John F. Stetson All Rights Reserved ------------------------------------------------------------------------ Contents ------------------------------------------------------------------------ 1.0 INTRODUCTION 1.1 Program Requirements 1.2 Design Philosophy 2.0 PROGRAM USAGE 2.1 Installation 2.2 Activation 2.3 Execution 2.4 Termination 2.5 Removal 3.0 APPENDICES 3.1 Switch Differences 3.2 Configuration 3.3 Error Messages ------------------------------------------------------------------------ 1.1 Program Requirements ------------------------------------------------------------------------ SDR.COM is a memory resident sorted directory utility program which operates on IBM-PC compatible computer systems using the IBM PC-DOS or Microsoft MS-DOS Operating System Version 2.0 or higher. SD.COM is the non-memory resident version of the program. Since the capabilities and command syntax of the two programs are virtually identical, only the differences and additional capabilities of SDR.COM are covered in this document. It is recommended that the user first become familiar with the use of SD.COM before using SDR.COM. The bulk of the command syntax for SDR.COM is therefore covered in the document for SD.COM. This version of the program requires about 16Kb of disk space and about 24-68Kb of memory during execution, depending on the size of the directory, file and screen buffers configured by the user. With the default buffer sizes, the program uses about 32Kb of system memory. Support is provided for IBM-PC compatible MDA, CGA, MCGA, EGA, and VGA video adaptors and monitors. ------------------------------------------------------------------------ 1.2 Design Philosophy ------------------------------------------------------------------------ As is the case for SD.COM, SDR.COM provides more information than the resident DOS DIR command about the files on a disk, and allows the user to select, sort, format, and display the information in a variety of ways. This is accomplished by specifying a pattern name to select the desired files and by specifying any of a variety of command line "switches" which allow you to modify the behavior of the program. The switch names have been designed using letters, as much as possible, so that it is easier to associate the function of a switch with its name. In addition, the default switch values have been carefully chosen to reflect their most common use. The advantage of a memory resident program is that it is almost always available for use, regardless of the other program(s) currently running. Otherwise, it would be necessary to either exit the current program and return to the DOS system command prompt in order to run the program, or use the "shell" facility that some programs provide to execute other programs and then regain control. Since not all programs provide this capability, having your frequently used utilities in memory resident form greatly increases their availability. In addition, execution of a memory resident program is virtually instantaneous, since the program is only loaded from disk once. The primary disadvantage of a memory resident program is that it consumes system memory which would otherwise be available to execute other programs. Most memory resident programs are loaded once at system boot time and remain in memory permanently. Well designed memory resident programs are carefully written to minimize the amount of memory they use, and allow the user to configure the program to achieve a good balance between functionality and memory consumption. Another more subtle disadvantage is that most non-trivial memory resident programs must employ a variety of techniques to work around the limitations in the DOS operating system and the IBM-PC BIOS. Since there is not yet a universally accepted standard for what these techniques should be, there is no guarantee that any one memory resident program will be compatible with another, or even with other non-memory resident programs. However, enough of a standard has emerged to write useful memory resident programs, and the benefits of frequently used programs greatly outweigh the occasional incompatibilities for most users. This program has been designed in such a way as to try and maximize its compatibility with other programs. However, there is no guarantee that incompatibilities will not arise with a specific program. When this occurs, a good strategy to follow is to try to simplify the environment as much as possible; remove other memory resident programs one at a time, or try changing the order in which they are loaded. ------------------------------------------------------------------------ 2.1 Installation ------------------------------------------------------------------------ Unlike non-memory resident programs, SDR is normally only executed once, immediately after the operating system is booted. This is best done by placing the command "SDR" in the AUTOEXEC.BAT file which is automatically executed by DOS after boot-up. As mentioned above, it may be necessary to experiment with different loading orders of multiple Terminate-and-Stay-Resident programs. In general, the more complex TSR type programs (such as BORLAND's SideKick) should be loaded after simpler TSR programs. Like most TSR programs, SDR should only be installed at the top DOS command level, not from inside another program. There are two SDR DOS command line switches (/q and /z) which may be specified at installation time. A third switch (/r) is used to remove the program from memory and is described below. These switches should not be confused with those used once you have activated the program and are operating inside it. The help screen displayed in response to the /? switch (inside SDR) flags these switches with an (*) character as a reminder that they are to be used on the DOS (not the SDR) command line. The /q switch requests "quiet" installation mode. Normally, if the installation is successful, SDR will display a message in a box showing the total amount of memory it is using and the activation key sequence. This message cannot be suppressed by redirecting it to the DOS "NUL" device, since it is not displayed using standard DOS video services. Specifying the /q switch will prevent the message from being displayed. Similarly, the /z switch causes suppression of the message box which is normally displayed when the program is activated by pressing the hot key sequence. See the sections below for additional information. As an example, you can install SDR and suppress both message boxes as follows: D>SDR /Q/Z Although it is rather unlikely, installation of SDR can be denied for the following reasons: 1) DOS 2.0 or later is required. 2) The program has already been loaded into memory. 3) The directory or file buffer sizes requested are out of bounds. The program was incorrectly patched - this can't happen if the available configuration program (SDC) is used. 4) There is insufficient system memory available for the resident code, data, directory and file buffers. 5) The program is unable to release memory it no longer needs. 6) The program is unable to allocate memory for the screen buffer. ------------------------------------------------------------------------ 2.2 Activation ------------------------------------------------------------------------ Since the program is "memory resident", it is available for use even though another program is currently running. The program is activated by pressing the activation or "hot" key combination. The default activation key combination is CTRL-ESC (while holding down the CTRL key, press the ESC key at the same time). These key combinations can be changed using the configuration program so as not to conflict with their possible use by other programs. Although the program will usually be able to "go active" or "pop up", there are a few situations where this is not possible (or desirable!): 1) If the program is already active. Pressing the activation key while inside the program is sometimes used to exit a TSR program. Since a different key (ESC) is used for this purpose in SDR, this is not allowed. 2) If Disk I/O is in progress. Although not recommended, you may find that you can safely pop up SDR in the middle of reading or writing to a disk. At other times, the request may be denied. This is due to the need to serialize access to non-reentrant code in the PC BIOS. 3) If the current video mode is either 40 column text or graphics. Since SDR requires the full width of the screen in 80 column text mode, it will decline to activate if the current video mode is incompatible with these requirements. The primary programs which use these video modes are BASIC programs. 4) If a multitasking environment such as Microsoft Windows or DESQview is currently being used. Since these environments involve complex memory management functions, you should use SD rather than SDR. You CAN use SDR with Windows/386 if you install it while inside Windows. In the situations above, the activation request will be acknowledged by an audible tone or "beep", so that there is no doubt that the request was declined. However, there is another situation where the program may not appear to activate. Some programs or commands may perform certain long-running functions which do not provide an opportunity for TSR programs to activate. A simple example is the TYPE command. If you type a large file and press the activation key during the output, the program will probably not go active and the audible tone will not be generated. However, when the command ends, either normally or by a CTRL-BREAK interrupt, SDR will activate. Some TSR programs simply refuse to activate in this situation. Another similar situation can occur when one TSR program is already active and refuses to allow a second TSR program to even "see" its hot- key sequence. This is a characteristic of "ill-behaved" TSR programs which are all too common. Yet another scenario occurs when SDR "pops- up" over another TSR program but appears to be "dead". Sometimes simply pressing a few keys will cause the "deadly embrace" to end, although these keys may be passed back to the previously invoked program. Since SDR dynamically determines the video configuration, this means that you can install it using one kind of video monitor and activate it from another kind. You can switch between MDA, CGA, and EGA or VGA monitors at will and SDR will adapt its operation to the monitor in use. ------------------------------------------------------------------------ 2.3 Execution ------------------------------------------------------------------------ After the activation key is accepted, the program "goes active" or "pops up". At this point, the top few lines of the screen are cleared and a box with several lines of information is displayed. A prompt appears on the screen line below the box. Once you are familiar with the operation of the program, you may wish to use the SDR DOS command line /z switch to eliminate the box in order to save screen space. The following options are now available: 1) Enter a valid command line. See below for details. 2) Press the RETURN key to display the current directory. 3) Enter /? to display command help information. 4) Press ESC or CTRL-C to return to the suspended program. The complete form of the command line is: D:\path> [/switches] [drive][path][filespec] [/switches] The prompt string consists of the current drive letter, followed by the current directory path for the drive, followed by the prompt character (which may be configured). The SDR prompt may appear alarmingly similar to your DOS system prompt; the DOS command: PROMPT $P$G generates the same type of prompt string. To avoid confusion, SDR allows the prompt character to be changed, and the default is a graphics character different from the usual (>) character. The rest of the command line parameters (drive, path, filespec, and switches) are just like those accepted by the SD.COM program. Please refer to the documentation for SD for details. The command line must be terminated by the RETURN or ENTER key. The Backspace key may be used to remove previously typed characters on the command line. Since SDR must avoid the use of DOS console services in resident code, utilities like PCED, CED, and DOSEDIT which allow editing the DOS command line will unfortunately not function inside SDR. After the output of the current command is displayed, the prompt string is redisplayed. This allows you to enter as many commands as desired before returning to the suspended program. Keep in mind that the program which was in control when the activation key was pressed is in a suspended state; this implies that you will not wish to activate SDR (even though it is allowed) when executing a time-critical program. A good example of this is a modem communication program which is in the middle of a file transfer with a remote system. To see SDR in operation, try the following example: 1) Execute the BASIC language interpreter with the command: BASICA 2) Enter the following BASIC command: FOR I=1 TO 999 : ? I,SQR(I) : NEXT 3) Press RETURN and wait until the screen fills 4) Press the SDR activation keys: CTRL-ESC 5) Press RETURN several times to display the directory 6) Press ESC to return to the BASIC program 7) Notice that the program picks up where it left off 8) Press CTRL-BREAK to terminate the BASIC program Unlike most programs, you can't type ahead while the program is running. This is due to the need to monitor the keyboard in order to pause the screen output. If you wish to begin typing a new command, simply press ESCAPE (preferred) or Control-C to immediately terminate the output, and then type the next command. Console output may be paused by typing any other character and may be restarted in two different ways. If RETURN is pressed, screen output resumes until the either the screen fills or the output finishes. If any other character is typed, only a single line of additional screen output is displayed. This allows you to easily control the displayed output so as to minimize the loss of existing screen data by scrolling. The recommended single line scroll keys are the Space Bar or Down Arrow. ------------------------------------------------------------------------ 2.4 Termination ------------------------------------------------------------------------ The only way to exit from SDR to the suspended program is by pressing the ESC or CTRL-C key from the SDR command prompt. Pressing CTRL-BREAK will not exit from SDR and will appear to be ignored, but the interrupt may be seen by the suspended program when SDR is exited normally. If the ESC key is used to exit from SDR, the console screen is restored to its original state, and the cursor position and size are restored to their original state when the original program was suspended. If the CTRL-C key is used to exit from SDR and the original screen line containing the cursor before SDR was activated is still visible, the cursor is restored to its original state, but the screen is NOT restored. A divider line is displayed over the last SDR prompt line to clearly separate the original and subsequent screen output. The reason for this behavior is to allow you to retain output generated by SDR in order to be able to refer to it when you return to the suspended program. Once the original cursor line is overwritten, either by screen output, scrolling, or clearing the screen, CTRL-C will cause the entire screen to be restored, just like ESC. Therefore, if you plan to use this feature, you will want to position the cursor as close to the bottom of the screen as possible before activating SDR. Once you have referred to the SDR output, you may wish to perform an action in the suspended program which will cause the screen to be rewritten, in order to avoid confusion and to resynchronize the display. ------------------------------------------------------------------------ 2.5 Removal ------------------------------------------------------------------------ SDR prevents the user from loading multiple copies of itself in order to avoid wasting memory. It can be removed from memory by running it again with the /r command line switch specified. This is helpful when the program is being configured for different screen colors, etc. in order to avoid a system reboot to load a new copy of the program. It can also be useful if the need arises to release as much memory as possible for some other purpose. Although it is rather unlikely, removal of SDR can be denied for the following reasons: 1) The program is not already loaded in memory. 2) Interrupt vectors previously saved and changed by the program have been subsequently altered by another program. 3) The program is unable to release memory it no longer needs. SDR will decline to remove itself from memory if it determines that another TSR program has stolen one of the interrupt vectors which it saves and then changes. In this case, you must remove the other program from memory before you can remove SDR. A good example is when BORLAND's SideKick utility is used with SDR. In this case, install SDR first and SideKick second. You must remove SideKick first, and SDR second. This is necessary since SideKick constantly monitors the interrupt vectors it steals and if it detects that another program has stolen them, it steals them back again! Although a few TSR programs provide a means of deinstalling themselves from memory (such as SDR), most do not. However, there are several utilities available which provide this capability. MARK and RELEASE by TurboPower Software and INSTALL and REMOVE by PC Magazine are readily available on many bulletin boards. These programs require that you execute a special program before installing a TSR program, and another program when you wish to remove the TSR program. They work by saving information about the state of the Interrupt Vector Table and DOS Memory Control Blocks so that this information can be subsequently restored, thus effectively removing the TSR program. There are also several utility programs available which display all of the currently loaded TSR programs, along with information on how much memory they use, which interrupts they "steal", etc. By observing which interrupts are stolen by each TSR program, it is possible to determine which programs are likely to conflict with each other. If you use one of these programs to display the currently loaded TSR programs, you may notice that some are identified by their program names and some are not. Starting with DOS V3, the path and program name used to execute a program are stored in the program environment memory block. It is generally considered good practice for a TSR program to release this environment block (usually less than 100 bytes) at the time it is installed, and SDR does this. A side effect of this action is that programs which scan the memory control blocks and display information about TSR programs cannot obtain the program name. When any TSR program is removed from memory and it is not the last loaded TSR program, a gap in memory will result from the creation of the resulting free memory block. DOS will not normally be able to use this memory unless all TSR programs above it are first removed. This implies that TSR programs should always be removed in the opposite order in which they were installed, in order to maximize the use of available memory for other programs. ------------------------------------------------------------------------ 3.1 Switch Differences ------------------------------------------------------------------------ Although most of the command line switches function the same in SDR as they do in SD, there are differences due to the operating environment. Although the /e switch may still be used to clear the screen before the execution of an individual command, using the SDC program to turn this switch ON as a default will cause the entire screen to be cleared each time SDR "pops-up", but not automatically for each subsequent command. The Environment Size, TSR Memory, and System Memory Used and Free values displayed by the /i switch reflect the system memory at the time just after SDR was installed and may be incorrect if other TSR programs have been subsequently loaded. SDR will not be able to read the Boot Sector for drives above C: when it is activated from the DOS command prompt (rather than when inside most other programs). In this case, some of the disk parameter values will appear as NONE or zeros. The /q switch requests "quiet" installation of SDR when specified on the DOS command line as described above. When used inside SDR, it functions just as it does in SD to generate "quick" output without user prompts. The /r switch is normally used in SD to allow the program output to be redirected to a file or to the printer. Since this function is performed by the DOS command interpreter, it is not available inside a memory resident program. The /r switch is used to remove SDR from memory (when specified on the DOS command line to execute SDR), and is ignored if it is specified on the command line inside SDR. The /w switch resets the screen to 25 lines after the execution of the current command in SDR, NOT when SDR returns to the suspended program. The /z switch is normally used in SD to cause the screen to be saved and restored. When specified on the SDR DOS command line, it suppresses the activation message box. If you often use the CTRL-C key to exit from SDR, you may wish to specify /z when installing SDR so that you have more room to use on the screen. The /z switch is ignored if it is specified on the command line inside SDR. The SD /$ switch, which is designed to facilitate the operation of SD when it is executed inside a DOS Batch file, is not implemented in SDR. The EGA and VGA switches (/25, /35, /43, /50) should be used cautiously. If you use an EGA or VGA video adaptor and wish to use more than 25 screen lines, make sure you select screen buffer type 2 (8000 bytes) in the configuration program. Otherwise, only the first 25 lines of the original screen will be restored. Even so, it is recommended that you reset the screen to its original size before returning to the suspended program, unless it is known to be able to tolerate this kind of dynamic video mode switching. It should be kept in mind that SDR has several restrictions placed on it which do not apply to the simpler operating environment of SD. Even though SDR can be activated from the DOS command prompt, you may prefer to use SD in this situation for the following reasons: 1) Previous screen output is more readily visible. 2) More directories and files can be processed. 3) Output may be redirected to a file or device. 4) Full disk parameter information for drives above C: is available when requested by the /i switch. SDR should therefore not be viewed as a total replacement for SD, but as a supplementary program which is available in more environments. ------------------------------------------------------------------------ 3.2 Configuration ------------------------------------------------------------------------ The SDR program may be configured (using SDC) or patched (using DEBUG) to change the various program defaults to those you prefer. The SDC program is preferred over DEBUG since it is much easier and safer to use and allows you to decide which combination of screen colors you prefer. It also allows you to first configure the SD program for the default switches and screen colors you prefer and to then transfer these values to the SDR program, without having to leave the configuration program. You will then only have to configure the options which are unique to SDR. Run the DEMO2.BAT file to see some examples of the SDC program. If you are using DEBUG, you will need to refer to the section titled Patch Area Format in the SD.DOC file to obtain the necessary offsets and data values. Activation Key Specification Great care should be taken in selecting the activation or hot key sequence. It must be unique enough that it will never be needed for any other purpose by any program you normally use. This usually means that an ALT or CTRL key combination is the best choice. For PC-AT style keyboards, the SysReq key cannot be used as a hot key since it is processed differently from the other standard keys. The new keys on enhanced 101 key keyboards such as F11 and F12 also cannot be used since they are processed differently by the ROM BIOS. Hot Key Control Codes (select any combination from 0-15) 1 = Right Shift Key 4 = Ctrl Key 2 = Left Shift Key 8 = Alt Key The default hot key control code is 4 (CTRL). Hot Key Scan Codes (select any value from 0-255) Escape = 01 Home = 71 Shift F1-F10 = 84- 93 1234567890-= = 02-13 Up Arrow = 72 Ctrl F1-F10 = 94-103 Back Space = 14 Page Up = 73 Alt F1-F10 = 104-113 Tab = 15 Left Arrow = 75 Ctrl PrtSc = 114 QWERTYUIOP[] = 16-27 Right Arrow = 77 Ctrl Left Arrow = 115 Enter = 28 Keypad + = 78 Ctrl Right Arrow = 116 ASDFGHJKL;'` = 30-41 End = 79 Ctrl End = 117 \ZXCVBNM,./ = 43-53 Down Arrow = 80 Ctrl PgDn = 118 * = 55 Page Down = 81 Ctrl Home = 119 Space = 57 Insert = 82 Alt 1234567890-= = 120-131 F1-F10 = 59-68 Delete = 83 Ctrl Pgup = 132 The default hot key scan code is 1 (ESC). Hot Key String You may enter a character string of from 1 to 16 characters which will be displayed as part of the program's installation message as a reminder of the hot key sequence. The default hot key string is CTRL-ESCAPE Keys. If you use DEBUG, make sure that the string is padded with trailing spaces through the 16th character, if necessary, and that the next character is a NULL (hexadecimal 00). Prompt Character Specification The default prompt character (code 26, a graphics right arrow symbol) was chosen to be different from, but similar to the standard DOS command line prompt character. You may change it to any standard or extended ASCII character from 0-255. SDR Memory Usage Dir Buffer Minimum Default Maximum ---------- ------- ------- ------- Bytes 512 1024 4096 Dirs 32 64 256 File Buffer Minimum Default Maximum ----------- ------- ------- ------- Bytes 2560 10240 40960 Files 102 409 1638 ARC Files 88 353 1412 Memory Usage Minimum Default Maximum ------------ ------- ------- ------- Code & Data 16928 16928 16928 Dir Buffer 512 1024 4096 File Buffer 2560 10240 40960 Screen Buffer 4000 4000 8000 Total 24000 32192 69984 Buffer Size Specifications The choice of the directory and file buffer size values is based on a trade-off between minimizing the amount of memory used and allowing for a reasonable number of directories and files. Each directory buffer entry uses a variable number of bytes from 4 to 70, depending on the length of the directory name. For the purposes of performing some calculations, we will assume an average directory name length of 13 characters, or 16 bytes per directory buffer entry. Each file buffer entry uses 25 bytes per file or 29 bytes for files inside ARC files. The default buffer sizes are 1024 bytes for about 64 directory entries and 10240 bytes for about 409 files/directory or 353 files/ARC file. The directory buffer is only used when processing global directories with the /g switch. Its size may range from 512 to 4096 bytes. The file buffer is always used and contains all of the file and subdirectory names for an individual directory or ARC file. Its size may range from 2560 to 40960 bytes. The size of the resident code and data excluding these two buffers is currently about 16928 bytes. The buffer used to save the screen may be configured for either 4000 or 8000 bytes. You can therefore configure the program to use as little as about 24Kb of memory or as much as about 68Kb. The total memory used not including the screen buffer must be less than 64Kb. This limit is strictly enforced; you will receive the "Memory error" message when installing SDR if the total configured memory size exceeds this. If you attempt to exceed the configured buffer size limits when running the program, you will receive the "Too many dirs" or "Too many files" message, and the resulting output will be incomplete. The default screen buffer size is 4000 bytes. This is sufficient for either a Monochrome or CGA equipped PC. However, if you use an EGA or VGA monitor and sometimes use more than 25 lines on the screen, you may wish to configure an 8000 byte screen buffer to allow for up to 50 lines of 80 characters. Failure to do this will result in only the first 25 screen lines being restored. ------------------------------------------------------------------------ 3.3 Error Messages ------------------------------------------------------------------------ The following error messages are displayed and system return codes set for various conditions which may arise. An audible tone is generated to alert the user of severe errors. The return codes may be tested using the standard DOS IF ERRORLEVEL statement in a .BAT file. No matching files (directory may be empty) Bad switch (use /? for help information) Bad drive (doesn't exist or syntax error) Bad path (doesn't exist or syntax error) Bad filespec (syntax error) Bad date (too large or syntax error) Too many dirs (buffer limit exceeded for /g) Too many files (buffer limit exceeded) Disk error (floppy disk may not be in drive) 0 - Removed (in response to /r switch) 1 - Already loaded (can't reload unless removed) 2 - Not loaded (can't remove unless loaded) 3 - Can't remove (interrupt vectors changed) 4 - Memory error (insufficient or (de)allocation problem) ------------------------------------------------------------------------ IBM and PC-DOS are trademarks of IBM Corporation. MICROSOFT and MS-DOS are trademarks of Microsoft Corporation. DESQview is a trademark of Quarterdeck Office Systems. SideKick is a trademark of BORLAND International Corporation. ARC is a trademark of SEA Corporation. ------------------------------------------------------------------------